<?php
/**
 * Copyright (c) 2008, Till Klampaeckel
 * 
 * All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 * 
 *  * Redistributions of source code must retain the above copyright notice, this
 *    list of conditions and the following disclaimer.
 *  * Redistributions in binary form must reproduce the above copyright notice, this
 *    list of conditions and the following disclaimer in the documentation and/or
 *    other materials provided with the distribution.
 * 
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * PHP Version 5
 *
 * @category Services
 * @package  Services_Plazes
 * @author   Till Klampaeckel <till@php.net>
 * @license  http://www.opensource.org/licenses/bsd-license.php The BSD License
 * @version  CVS: $Id$
 * @link     http://code.google.com/p/servicesplazes/
 */
 
/**
 * Services_Plazes_Adapter_Activities_Exception
 */
require_once 'Services/Plazes/Adapter/Activities/Exception.php';

/**
 * A class to interface the API of plazes.com.
 *
 * @category Services
 * @package  Services_Plazes
 * @author   Till Klampaeckel <till@php.net>
 * @license  http://www.opensource.org/licenses/bsd-license.php The BSD License
 * @version  Release: @package_version@
 * @link     http://code.google.com/p/servicesplazes/
 */
final class Services_Plazes_Adapter_Activities extends Services_Plazes
{
    /**
     * __construct
     */
    private function __construct()
    {
    }
    
    /**
     * factory
     *
     * @param array $params Params passed in from Services_Plazes.
     *
     * @return Services_Plazes_Adapter_Activities
     */
    static function factory($params)
    {
        $activities = new Services_Plazes_Adapter_Activities;
        $activities->setParams($params);
        
        return $activities;
    }
    
    /**
     * getActivities
     *
     * Gets activities, if you supply an ID it will get the activities
     * of the currently authenticated user.
     *
     * @param mixed $id The plazes user ID.
     *
     * @return array
     */
    public function getActivities($id = null)
    {
        $url    = $this->endpoint;
        $method = 'GET';
        if ($id === null) {
            $url .= '/activities.' . $this->responseFormat;
        } else {
            $url .= '/users/' . $id . '/activities.' . $this->responseFormat;
        }
        try {
            $response = $this->makeRequest($url, $method);
        } catch (Services_Plazes_Adapter_Exception $e) {
            throw new Services_Plazes_Adapter_Activities_Exception(
                $e->getMessage(),
                $e->getCode()
            );
        }
        return $this->_parseResponse($response);
    }
    
    /**
     * createActivity
     *
     * Create an activity. At the minimum we currently require a plaze_id.
     *
     * @param array $params Parameters used to create an activity.
     *
     * @return array
     * @throws Services_Plazes_Adapter_Activities_Exception Re-throw.
     * @todo   Utilize "feeling lucky" feature of the plazes API
     */
    public function createActivity($params)
    {
        if (!isset($params['plaze_id'])) {
            throw new Services_Plazes_Adapter_Activities_Exception(
                'Please supply a plaze_id.',
                Services_Plazes::ERR_MISSING_PARAM
            );
        }
        if (!isset($params['status'])) {
            $params['status'] = '';
        }
        
        $url = $this->endpoint . '/activities.xml';
        
        $xml = '<activity>';
        foreach ($params as $key=>$value) {
            $key  = strtolower($key);
            $xml .= '<' . $key . '>' . $value . '</' . $key . '>';
        }
        $xml .= '</activity>';

        try {
            $response = $this->makeRequest($url, 'POST', $xml);
        } catch (Services_Plazes_Adapter_Exception $e) {
            throw new Services_Plazes_Adapter_Activities_Exception(
                $e->getMessage(),
                $e->getCode()
            );
        }
        return $this->_parseResponse($response);
    }
    
    /**
     * deleteActivity
     *
     * Delete an activity of the currently authenticated user.
     *
     * @param int $id The ID of the activity.
     *
     * @return boolean
     * @throws Services_Plazes_Adapter_Activities_Exception Re-throw.
     */
    public function deleteActivity($id)
    {
        $url = $this->endpoint . '/activities/' . $id . '.' . $this->responseFormat;
        try {
            $response = $this->makeRequest($url, 'DELETE');
        } catch(Services_Plazes_Adapter_Exception $e) {
            throw new Services_Plazes_Adapter_Activities_Exception(
                $e->getMessage(),
                $e->getCode()
            );
        }
        return true;
    }
    
    /**
     * getActivity
     *
     * Get all information about a specific activity.
     *
     * @param int $id The ID of the activity.
     *
     * @return array
     * @throws Services_Plazes_Adapter_Activities_Exception Re-throw.
     */
    public function getActivity($id)
    {
        $url = $this->endpoint . '/activities/' . $id . '.' . $this->responseFormat;
        try {
            $response = $this->makeRequest($url, 'GET');
        } catch (Services_Plazes_Adapter_Exception $e) {
            throw new Services_Plazes_Adapter_Activities_Exception(
                $e->getMessage(),
                $e->getCode()
            );
        }
        return $this->_parseResponse($response);
    }

    /**
     * getActivitiesByPlaze
     *
     * Return all activites at a certain pla[c,z]e.
     *
     * @param int $id The ID of the activity.
     * 
     * @return array
     * @throws Services_Plazes_Adapter_Activities_Exception Re-throw.
     */
    public function getActivitiesByPlaze($id)
    {
        $url  = $this->endpoint . '/plazes/' . $id;
        $url .= '/activities.' . $this->responseFormat;
        
        try {
            $response = $this->makeRequest($url, 'GET');
        } catch(Services_Plazes_Adapter_Exception $e) {
            throw new Services_Plazes_Adapter_Activities_Exception(
                $e->getMessage(),
                $e->getCode()
            );
        }
        return $this->_parseResponse($response);
    }
    
    /**
     * getActivitiesByUser
     *
     * Returns all current activites by user ID.
     *
     * Available flags are false (for all current activities), future, past and next
     * for the most relevant (aka the "next") activity.
     *
     * @param int   $id   The plazes user ID.
     * @param mixed $flag Flag - see above.
     *
     * @return array
     * @throws Services_Plazes_Adapter_Activities_Exception Re-throw.
     */
    public function getActivitiesByUser($id, $flag = false)
    {
        $url = $this->endpoint . '/users/' . $id;
        if ($flag === false) {
            $url .= '/activities.' . $this->responseFormat;
        } elseif ($flag == 'future') {
            $url .= '/future_activities.' . $this->responseFormat;
        } elseif ($flag == 'past') {
            $url .= '/past_activities.' . $this->responseFormat;
        } elseif ($flag == 'next') {
            $url .= '/activity.' . $this->responseFormat;
        } else {
            throw new Services_Plazes_Adapter_Activities_Exception(
                'Unknown mode/flag: ' . $flag,
                Services_Plazes::ERR_PARAM
            );
        }
        try {
            $response = $this->makeRequest($url, 'GET');
        } catch (Services_Plazes_Adapter_Exception $e) {
            throw new Services_Plazes_Adapter_Activities_Exception(
                $e->getMessage(),
                $e->getCode()
            );
        }
        return $this->_parseResponse($response);
    }
    
    /**
     * _parseResponse
     *
     * @param string $response The response received from the plazes API.
     *
     * @return array
     */
    private function _parseResponse($response)
    {
        if ($this->responseFormat != 'xml') {
            return $response;
        }
        
        $simpleXml = simplexml_load_string($response);
        return (array) $simpleXml;
    }
}
?>
